home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 6 / Amiga Format AFCD06 (Nov 1996, Issue 90).iso / serious / commercial / xfa_devkit / xfa_library.doc < prev    next >
Text File  |  1996-08-19  |  40KB  |  1,469 lines
  1. ******************************************************************************
  2.  
  3.     XFA developer's kit, not for commercial use.
  4.     XFA.library Concept/Code/Design by Michele Puccini.
  5.  
  6.     All rights reserved by:
  7.     ClassX Development Italy
  8.     Via Francesca 463, I-56030 Montecalvoli (PI)
  9.     Tel: +39 587 749206
  10.     Fax: +39 587 749206
  11.     E-Mail: classx@pisoft.it (Michele Puccini)
  12.  
  13.     Feel free to contact us for any further information.
  14.  
  15. ******************************************************************************
  16.  
  17.     IMPORTANT:
  18.     This library is FreeWare, and NOT FOR COMMERCIAL PUPOSES.
  19.     If you write an application that makes use of this library, you
  20.     are kindly requested to let me know and to give me one copy of
  21.     what you've developed.
  22.     This library cannot be used for commercial products without written
  23.     permission of ClassX Development Italy.
  24.  
  25. ******************************************************************************
  26.  
  27. Standard Disclaimer
  28. *******************
  29.  
  30. THERE IS NO WARRANTY FOR THE SOFTWARE TO THE EXTENT PERMITTED BY APPLICABLE
  31. LAW.  EXCEPT WHERE OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
  32. OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
  33. EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  34. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE
  35. ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
  36. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  37. SERVICING, REPAIR OR CORRECTION.
  38.  
  39. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
  40. ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE SOFTWARE
  41. AS PERMITTED BELOW, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
  42. SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
  43. INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
  44. DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES
  45. OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
  46. SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  47. DAMAGES.
  48.  
  49. ******************************************************************************
  50. Introduction
  51.  
  52. - Another NON-STANDARD animation format, why ?
  53. Well, during the development of X-DVE, our titling/animation system, one of
  54. the first problems I had to face was to choose an animation format suited
  55. for video resolutions (meaning both PAL and NTSC) fast enough to play 
  56. smooth, even with high resolution and "deep" screens.
  57. I started to test the various standard animation formats, like Anim-5, Anim-7
  58. etc.
  59. They were all too slow to play and gave other extra features (like multiple
  60. palette handling, multi frame rates, complete multitasking) which I could 
  61. stand without.
  62. The only anim format very near to my requirements was SCALA's anim 32I, but:
  63. - there was no documentation for it.
  64. - it was smooth enough, but trying to swith caches off (68040) display
  65. started to flash, making me think of a bad double buffering tecnique.
  66. So, I decided to start working on a new compression tecnique (XFA) that
  67. now is in your hands.
  68.  
  69. - What kind of tecnique is used in XFA ?
  70. The tecnique is the classic "delta frame compression" that is normally used
  71. for anim-5, anim-7 formats.
  72.  
  73. XFA animations can be of 4 different kinds:
  74.  
  75. MODE                COMPRESSION                DISPLAY                    NOTE
  76. XFA_MODE16        16 bit                     ANY(forced to PAL)    right for disk play
  77. XFA_MODE32        32 bit                     ANY(forced to PAL)    right for disk play
  78. XFA_MODE16I     16 bit                     PAL/NTSC Lace
  79. XFA_MODE32I     32 bit                     PAL/NTSC Lace
  80.  
  81. While MODE16 and MODE32 can be played from disk and in any screen mode,
  82. MODE16I and MODE32I offers a better compression but can only be played
  83. in PAL or NTSC interlaced screens (this is what I need for VIDEO applications)
  84. The "I" modes are expressely developed to run at 50fps (PAL) and MUST run
  85. at 50fps (the only way to see smooth animations)
  86. The difference from anim-5/7 is that XFA deltas can be decompressed with a
  87. small (can be totally cached), fast and furious asm routine that outperforms
  88. any comparable standard decompression routine.
  89. Another difference is that, for "16I & 32I" modes, only half information
  90. is compressed for each frame, (nearly) doubling the decompression speed and 
  91. (nearly) halving the size of each delta.
  92. Displaying XFA "16I & 32I" mode animations, involves some low-level work
  93. with copper lists, in order to achieve a solid double buffering, even when
  94. the CPU is not fast enough to decompress deltas in synch with the vertical
  95. beam.
  96.  
  97. ******************************************************************************
  98. Call for Developers
  99.  
  100. This library has been developed to allow flexible access to XFA animations.
  101. PD programmers are strongly encouraged to use this library as it has a "human"
  102. programming approach and interesting (I hope) performances.
  103. I Hope to see talented PD programmers using this library for players,
  104. converters and other related applications.
  105. The first application I hope to see in the next months is a complete XFA
  106. datatype (........even if this will not give 50fps XFA's, it will be beautiful
  107. to have a (Multi)View of this kind of format in an intuition window !)
  108. Thank you for reading and supporting.
  109. Feel free to contact me for suggestions/improvements/questions.
  110. I MUST remember that XFA animations can be possible only thanks to Amiga
  111. custom chips and its fantastic OS (...that's the way it is, mr. big blue)
  112. Last-Last-Last:  Italy is full of great Amiga talents but I really want
  113. to make a special thank to Fabio Rotondo for writing XFA_Util2 (no more
  114. excuses, the docs are here, now it's on you !)
  115.  
  116.  
  117.     My banner:
  118.  
  119.      // 
  120.     \X/ Amiga. Computers for Thinking People
  121.        ------------------------------------
  122.  
  123.                                                                     Michele Puccini
  124.  
  125.  
  126.  
  127. Further note:
  128. Today, 19 Aug 1996 no one other than me is using this library, even if it is
  129. stable and fully working from v1.00.
  130. With the v1.15 it is only a little more reliable but the core code is still
  131. the same of v1.00.
  132. Dear developer, take a look at the example code and tell me why you are not
  133. using xfa.library.
  134.  
  135. ******************************************************************************
  136. Revision History
  137.  
  138. * v1.0 (23 Ago 1995)
  139. - First release, official X-DVE 2.0 compression library
  140.  
  141. * v1.1  (5 Apr 1996)
  142. - Added OSCAN_VIDEO flag to the screens opened with XFA_OpenPlayStuff()
  143.  
  144. * v1.10 (15 Apr 1996)
  145. - Added NTSC support to the library
  146.  
  147. * v1.12 (27 Mag 1996)
  148. - Better XFA_OpenPlayStuff(): now it shows the screen only when it is
  149.   fully initialized (no more flashes).
  150.  
  151. - Better XFA_Play(): bitmaps no more cleared at startup (they are already
  152.   cleared).
  153.  
  154. - Better sprite handling, now it is turned off in the right way.
  155.  
  156. - (FIX) XFA_MODE16 and XFA_MODE32 OpenPlayStuff() now works (it always failed,
  157.   leaving the screens opened (mea culpa !!)).
  158.  
  159. * v1.14 (19 Lug 1996)
  160. - XFA_Play() now supports slow motion play (25fps in PAL, 30fps in NTSC).
  161.   Blame me: I've modified the FD for XFA_Play()
  162.  
  163. - Finally sprites are tuned off correclty !
  164.  
  165. * v1.15 (9 Ago 1996)
  166. - Added support for Virtual Memory Manager.
  167.  
  168.  
  169. ******************************************************************************
  170. ToDo
  171.  
  172. - Allow the use of XFA_LibErr() to detect errors.
  173. - Multipalette handling.
  174. - Remove Disable()/Forbid() calls.
  175. - Better compression/speed (XFA2 ?)
  176. - DiskPlay.
  177. - AsynchIO for IFF handling.
  178. - 
  179.  
  180. ******************************************************************************
  181. CPU-68000 WARNING
  182.  
  183. Developer's package includes library versions compiled for 68000/20/30/40.
  184. Animations packed with 68020+ libraries CANNOT BE PLAYED on a standard
  185. 68000 cpu, because of data alignment restrictions (you'll get an address
  186. error).
  187. So, if you want to play XFA animations on a basic 68000 Amiga, you must
  188. compress them with xfa.library for 68000 processors, that automatically
  189. generates 68000-compatible anims.
  190. Note that 68020,030,040 libraries are equivalent in size and code (I use
  191. no FPU code inside, (and no 680x0 specific code...)).
  192.  
  193.  
  194. ******************************************************************************
  195. EXAMPLES AND SUPPORT CODE
  196.  
  197. The example code is written in BlitzII which is powerful, simple and very
  198. near to C (well, not too much....).
  199. I suppose there will be no problems for C coders to read and understand it.
  200. C include files are supplied in the appropriate drawer but I've no time to
  201. give them a better "Amiga-Library-Standard" look (help will be appreciated).
  202. BlitzII include file is "LIB_XFA.BB" and must be included everytime you want
  203. to use xfa.library.
  204. For BlitzII users there is also "xfa.library1" file that MUST be put into
  205. "Blitz2:blitzlibs/amigalibs" drawer, in order to get access to xfa.library
  206. functions (DefLibs MUST also be updated with the MakeDefLibs proggie).
  207.  
  208. ******************************************************************************
  209. SPEED DEMONS READ THIS
  210.  
  211. XFA is really an extra fast animation format and, if you believe in
  212. miracles, you will obtain 256 colours super-hires overscan 1472x566
  213. 50fps animations with pictures floating on the screen an a basic A1200 ;)
  214. This surely is the dream of everyone involved in video production.
  215. If XFA could do this, I could surely take the Nobel for Computer Science !
  216. You know that this is impossible to obtain from today's personal computers
  217. expecially if they don't have some hot chips inside.
  218. Amiga display chips, are really the best for video applications, but they
  219. have to be updated, just to follow today's users requirements.
  220. If they were light years away from the silly CGA, they now suffer of some
  221. bottlenecks (slow clock, cpu stealing, dma saturation).
  222. Now figure this:
  223. to play an animation at 50fps you have to unpack 1 frame every 1/50s.
  224. If the animation is a simple 640x512x4bpl resolution, the maximum thoughput
  225. you have to substain is 640/8 * 512 * 4 bytes per 1/50s (163840 bytes) or
  226. 8.192.000 bytes/s.
  227. If the same animation is a 768x566x8bpl resolution througput is 21.734.400
  228. bytes/s.
  229. If you have a 1472x566x8bpl maximum througput is 41.657.600 bytes/s.
  230. That's (nearly) all, but you have also to consider:
  231. - if the unpack code is in chip mem, it runs much slower than in fast
  232. - if the unpack data is in chip mem, it is accessed slower than in fast
  233. - the destination bitmaps MUST be in chip mem
  234. - the more the resolution displayed, the slower the cpu (video dma steals
  235.   cycles to cpu, and you cannot figure how much this is true in super-hires).
  236. The situation can surely improve if cpu and gfxchips have separate fast clocks
  237. and ........ but this is another story.
  238. The main point is that HOWEVER Amiga makes full screen animations possible
  239. while the others keep on dreaming in front of their waving stamp-size 160x160
  240. (pre)views.
  241.  
  242. ******************************************************************************
  243. NOTE
  244.  
  245. This is the documentation of the functions included in xfa.library.
  246. They will surely appear to you a little bit "sparse" and sometimes
  247. lacking.
  248. Remember that xfa.libary has been developed for X-DVE, and not for you,
  249. so please accept some limitations (but feel free to ask me).
  250. These library functions are not lamer-proof. This means that parameters
  251. passed to a function are intended to be safe and consistent.
  252. This library has been tested with MungWall and Enforcer under OS 3.0, OS 3.1,
  253. OS2.0 and OS 2.1.
  254. The techniques used in this library are completely system-friendly (except
  255. for the fast bitmap doublebuffering under OS2.0 / OS2.1: an incredible
  256. trick to change a ViewPort's BitMap using a single MrgCop (don't ask me how)).
  257. To be honest I used to peek some copper lists, but this is _for_sure_ safe
  258. even if not so smart.
  259.  
  260.                             LOOK MA' ... NO ENFORCER HITS !
  261.  
  262. Suggestion: Be OS-Friendly! OS3.0+ allows to do everything you want
  263.                 without low-level programming and headaches.
  264.  
  265.  
  266. ******************************************************************************
  267. ******************************************************************************
  268. ******************************************************************************
  269. ******************************************************************************
  270. ******************************************************************************
  271.  
  272. ------------------------------------------------------------------------------
  273.  
  274. FUNCTION:
  275.  
  276.     XFA_LibErr()
  277.  
  278. PROTO:
  279.  
  280.     LONG __asm __saveds LIBXFA_LibErr(void);
  281.  
  282. ACTION:
  283.  
  284.     Returns the error code of the last library function that caused an error.
  285.  
  286. ARGUMENTS:
  287.  
  288.  
  289. BUGS:
  290.     
  291.  
  292. NOTES:
  293.  
  294.     Not currenlty used from xfa library (maybe the next version)
  295.  
  296. ------------------------------------------------------------------------------
  297.  
  298. FUNCTION:
  299.  
  300.     XFA_PackMem_W(src0,src1,dest,size,mode)
  301.  
  302. PROTO:
  303.  
  304.     LONG __asm __saveds LIBXFA_PackMem_W(register __a0 UWORD * , register __a1 UWORD * , register __a2 UBYTE * , register __d0 LONG , register __d1 BOOL );
  305.  
  306. ACTION:
  307.  
  308.     Packs the differences of 2 chunks of memory in XFA format (16 bit).
  309.     Returns the size of compressed memory in bytes.
  310.  
  311. ARGUMENTS:
  312.  
  313.     src0 =    pointer to source memory 0
  314.     src1 =    pointer to source memory 1
  315.     dest =    pointer to destination user-allocated memory
  316.     size =    size of "src" memory chunk to be compressed
  317.     mode =    FALSE:
  318.                 evaluate compressed size (safe! : it will not write to dest)
  319.                 TRUE:
  320.                 compress memory and write packed data to dest
  321.             
  322. BUGS:
  323.  
  324.     
  325. NOTE:
  326.  
  327.     This is low level function, not sensible to packmode set by XFA_SetPack().
  328.  
  329. ------------------------------------------------------------------------------
  330.  
  331. FUNCTION:
  332.  
  333.     XFA_PackMem_L(src0,src1,dest,size,mode)
  334.  
  335. PROTO:
  336.  
  337.     LONG __asm __saveds LIBXFA_PackMem_L(register __a0 ULONG * , register __a1 ULONG * , register __a2 UBYTE * , register __d0 LONG , register __d1 BOOL );
  338.  
  339. ACTION:
  340.  
  341.     Packs the differences of 2 chunks of memory in XFA format (32 bit).
  342.     Returns the size of compressed memory in bytes.
  343.  
  344. ARGUMENTS:
  345.  
  346.     src0 =    pointer to source memory 0
  347.     src1 =    pointer to source memory 1
  348.     dest =    pointer to destination user-allocated memory
  349.     size =    size of "src" memory chunk to be compressed
  350.     mode =    FALSE:
  351.                 evaluate compressed size (safe! : it will not write to dest)
  352.                 TRUE:
  353.                 compress memory and write packed data to dest
  354.             
  355. BUGS:
  356.  
  357.     
  358. NOTE:
  359.  
  360.     this is low level function, not sensible to packmode set by XFA_SetPack()
  361.  
  362. ------------------------------------------------------------------------------
  363.  
  364. FUNCTION:
  365.  
  366.     XFA_PackBitMap(sbitmap0,sbitmap1,dest,mode)
  367.  
  368. PROTO:
  369.  
  370.     LONG __asm __saveds LIBXFA_PackBitMap(register __a0 struct BitMap * , register __a1 struct BitMap * , register __a2 void * , register __d0 BOOL );
  371.  
  372. ACTION:
  373.  
  374.     Packs the differences of 2 bitmaps in XFA format according to the actual
  375.     packmode set by XFA_SetPack().
  376.     Returns the size of compressed memory in bytes.
  377.  
  378. ARGUMENTS:
  379.  
  380.     sbitmap0 =    pointer to source bitmap 0
  381.     sbitmap1 =    pointer to source bitmap 1
  382.     dest =        pointer to destination user-allocated memory
  383.     mode =        FALSE:
  384.                     evaluate compressed size (safe! : it will not write to dest)
  385.                     TRUE:
  386.                     compress memory and write packed data to dest
  387.             
  388. BUGS:
  389.  
  390.     
  391. NOTE:
  392.  
  393.     Bitmaps MUST be width/height/depth identical.
  394.  
  395. ------------------------------------------------------------------------------
  396.  
  397. FUNCTION:
  398.  
  399.     XFA_UnPackBitMap_W(bitmap,pkdata)
  400.  
  401. PROTO:
  402.  
  403.     LONG __asm LIBXFA_UnPackBitMap_W(register __a0 struct BitMap *bm, register __a1 UBYTE *pkdata);
  404.  
  405. ACTION:
  406.  
  407.     Unpacks the XFA delta pkdata into a bitmap (16 bit).
  408.     Returns the address of the next byte past the end of pkdata.
  409.     
  410. ARGUMENTS:
  411.  
  412.     bitmap =    pointer to destination bitmap
  413.     pkdata =    pointer to XFA 16 bit packed delta
  414.             
  415. BUGS:
  416.  
  417.     
  418. NOTE:
  419.  
  420.     This is low level function, not sensible to packmode set by XFA_SetPack().
  421.     Destination bitmap MUST be widht/height/depth identical of the one packed
  422.     in pkdata.
  423.  
  424. ------------------------------------------------------------------------------
  425.  
  426. FUNCTION:
  427.  
  428.     XFA_UnPackBitMap_L(bitmap,pkdata)
  429.  
  430. PROTO:
  431.  
  432.     LONG __asm LIBXFA_UnPackBitMap_L(register __a0 struct BitMap *bm, register __a1 UBYTE *pkdata);
  433.  
  434. ACTION:
  435.  
  436.     Unpacks the XFA delta pkdata into a bitmap (32 bit).
  437.     Returns the address of the next byte past the end of pkdata.
  438.     
  439. ARGUMENTS:
  440.  
  441.     bitmap =    pointer to destination bitmap
  442.     pkdata =    pointer to XFA 32 bit packed delta
  443.             
  444. BUGS:
  445.  
  446.     
  447. NOTE:
  448.  
  449.     This is low level function, not sensible to packmode set by XFA_SetPack().
  450.     Destination bitmap MUST be widht/height/depth identical of the one packed
  451.     in pkdata.
  452.  
  453. ------------------------------------------------------------------------------
  454.  
  455. FUNCTION:
  456.  
  457.     XFA_UnPackBitMap(bitmap,pkdata)
  458.  
  459. PROTO:
  460.  
  461.     LONG __asm __saveds LIBXFA_UnPackBitMap(register __a0 struct BitMap * , register __a1 void * );
  462.     Returns the address of the next byte past the end of pkdata.
  463.  
  464. ACTION:
  465.  
  466.     Unpacks the XFA delta pkdata into a bitmap according to actual packmode.
  467.     
  468. ARGUMENTS:
  469.  
  470.     bitmap =    pointer to destination bitmap
  471.     pkdata =    pointer to XFA packed delta
  472.             
  473. BUGS:
  474.  
  475.     
  476. NOTE:
  477.  
  478.     Destination bitmap MUST be widht/height/depth identical of the one packed
  479.     in pkdata.
  480.  
  481. ------------------------------------------------------------------------------
  482.  
  483. FUNCTION:
  484.  
  485.     XFA_SetPack(screen,packmode)
  486.  
  487. PROTO:
  488.  
  489.     void __asm __saveds LIBXFA_SetPack(register __a0 struct Screen * , register __d0 LONG );
  490.  
  491. ACTION:
  492.  
  493.     Sets internal memory areas according to the screen settings.
  494.     Sets the pack mode for those library functions sensible to packmode.
  495.     Fills internal XFA_Head structure according to screen settings.
  496.     Fills internal XFA_CMap structure according to screen settings.
  497.     
  498. ARGUMENTS:
  499.  
  500.     screen =        pointer to screen that will contain the frames to be packed
  501.     packmode =    XFA_MODE#? packing mode used from library functions
  502.             
  503. BUGS:
  504.  
  505.     
  506. NOTE:
  507.  
  508.     This function MUST be called before starting any compression, because
  509.     it will set all the stuff needed for packing frames.
  510.     It can be called also during the packing, just to change XFA_CMap struct
  511.     (useful to make changes to palette without affecting the frames).
  512.     Due to speed and AGA display restrictions, screen's bitmap->BytesPerRow
  513.     MUST be multiple of 8 (pixel width multipe of 64).
  514.     It is NOT safe to change compression mode or screen during the packing.
  515.  
  516. ------------------------------------------------------------------------------
  517.  
  518. FUNCTION:
  519.  
  520.     XFA_GetPackMode()
  521.  
  522. PROTO:
  523.  
  524.     LONG __asm __saveds LIBXFA_GetPackMode(void);
  525.  
  526. ACTION:
  527.  
  528.     Returns the actual packmode used by the library (XFA_MODE#?).
  529.     
  530. ARGUMENTS:
  531.  
  532.             
  533. BUGS:
  534.  
  535.     
  536. NOTE:
  537.  
  538.  
  539. ------------------------------------------------------------------------------
  540.  
  541. FUNCTION:
  542.  
  543.     XFA_OpenPackStuff()
  544.  
  545. PROTO:
  546.  
  547.     BOOL __asm __saveds LIBXFA_OpenPackStuff(void);
  548.  
  549. ACTION:
  550.  
  551.     Allocates all the stuff needed for packing a sequence of frames.
  552.     This function also tries to allocate an internal pack buffer to
  553.     speedup the packing.
  554.     Returns TRUE if allocation is OK or FALSE if something failed.
  555.     
  556. ARGUMENTS:
  557.  
  558.             
  559. BUGS:
  560.  
  561.     
  562. NOTE:
  563.  
  564.     This function returns TRUE even if the pack buffer cannot be allocated,
  565.     because this will affect only the packing speed.
  566.     So, allocation of speedup buffer is transparent, but memory-hungry Amigas
  567.     will be surely slower on packing frames.
  568.  
  569. ------------------------------------------------------------------------------
  570.  
  571. FUNCTION:
  572.  
  573.     XFA_ClosePackStuff(closemode)
  574.  
  575. PROTO:
  576.  
  577.     void __asm __saveds LIBXFA_ClosePackStuff(register __d0 LONG );
  578.  
  579. ACTION:
  580.  
  581.     Frees all the stuff allocated by XFA_OpenPackStuff, including
  582.     the eventual pack buffer.
  583.     
  584. ARGUMENTS:
  585.  
  586.     closemode =    modality for closing the animation (CLOSE_#?)
  587.             
  588. BUGS:
  589.  
  590.     
  591. NOTE:
  592.  
  593.     It is safe to call this function, even if the pack stuff is not allocated.
  594.     Actually the animation can be closed in 2 ways:
  595.     CLOSE_BLANK:
  596.         this means that, playing the animation, it will show the last two frames
  597.         completely cleared.
  598.     CLOSE_LOOP
  599.         this means that the animation can loop continuously without any
  600.         visible jumps (ex: a spinning title).
  601.     This function will not return any value, even if it would be better to
  602.     notify the user about a possible failure in packing the last 2 frames.
  603.     Note that CLOSE_LOOP mode, cannot close XFA_MODEI animations correcly when
  604.     there is a odd number of frames in memory.
  605.     The reason for this is very simple, as XFA_MODEI animations work with
  606.     screens divided in odd/even frames and to loop such animations, frames
  607.     must match odd/even sequence every loop.
  608.     An example ?:
  609.  
  610.     incorrect sequence (odd number of frames):
  611.  
  612.     frame0    frame1    frame2    frame2    frame3
  613.     odd        even        odd        even        odd
  614.  
  615.     (error, next loop you'll get another odd frame)
  616.  
  617.  
  618.     correct sequence (even number of frames):
  619.  
  620.     frame0    frame1    frame2    frame2    
  621.     odd        even        odd        even
  622.  
  623.     (ok, next loop you'll get the right odd frame)
  624.  
  625.     
  626. ------------------------------------------------------------------------------
  627.  
  628. FUNCTION:
  629.  
  630.     XFA_SetFramesArray(framesarray,numframes)
  631.  
  632. PROTO:
  633.  
  634.     void __asm __saveds LIBXFA_SetFramesArray(register __a0 struct Mem * , register __d0 LONG );
  635.  
  636. ACTION:
  637.  
  638.     Tells the library to use an extenal frames array.
  639.         
  640. ARGUMENTS:
  641.  
  642.     framesarray =    pointer to an externally allocated frames array
  643.     numframes =     number of frames that can be handled from the library
  644.                         (and the size of the frames array)
  645.             
  646. BUGS:
  647.  
  648.     
  649. NOTE:
  650.  
  651.     This function can be used if you want to have a custom frames sequence
  652.     or multiple frames sequencies in memory.
  653.     You also must take care of eventual deallocation of the frames array,
  654.     as XFA_FreeFrames cannot be used for this purpose (well, you can use it
  655.     if you allocate the frames array with AllocVec, but its is a trick and
  656.     can cause future incompatibility problems).
  657.     This function overwrites internal frames array pointer, so take care of
  658.     it, or you'll loose memory and animations.
  659.  
  660. ------------------------------------------------------------------------------
  661.  
  662. FUNCTION:
  663.  
  664.     XFA_AllocFrames(numframes)
  665.  
  666. PROTO:
  667.  
  668.     struct Mem * __asm __saveds LIBXFA_AllocFrames(register __d0 LONG );
  669.  
  670. ACTION:
  671.  
  672.     Allocates a frames array for pack or play.
  673.     Returns the (struct Mem *) pointer to the frames array or NULL if
  674.     allocation failed.
  675.         
  676. ARGUMENTS:
  677.  
  678.     numframes =     number of frames that can be handled from the library
  679.                         (and the size of the frames array)
  680.             
  681. BUGS:
  682.  
  683.     
  684. NOTE:
  685.  
  686.     It is allowed to allocate multiple frames arrays with this function,
  687.     since it does not free the currently used one.
  688.     If using this feature you MUST remember all the allocations done, in order
  689.     to free them before exiting the program.
  690.     
  691. ------------------------------------------------------------------------------
  692.  
  693. FUNCTION:
  694.  
  695.     XFA_FreeFrames()
  696.  
  697. PROTO:
  698.  
  699.     void __asm __saveds LIBXFA_FreeFrames(void);
  700.  
  701. ACTION:
  702.  
  703.     Free all the currently used animation frames (linked to frames array)
  704.     and the frames array created with XFA_AllocFrames().
  705.         
  706. ARGUMENTS:
  707.  
  708.  
  709. BUGS:
  710.  
  711.     
  712. NOTE:
  713.  
  714.     It is safe to call this, even if there is no frames array.
  715.     If you have multiple frames arrays, allocated with XFA_AllocFrames(),
  716.     you have some possibilities to free them:
  717.     suppose you have anim1 and anim2 allocated with XFA_AllocFrames()
  718.  
  719.     1)
  720.     XFA_SetFramesArray(anim1,anim1frames);
  721.     XFA_FreeFrames();
  722.  
  723.     XFA_SetFramesArray(anim2,anim2frames);
  724.     XFA_FreeFrames();
  725.  
  726.     2)
  727.     XFA_SetFramesArray(anim1,anim1frames);
  728.     XFA_FreeAnim();
  729.     FreeVec(anim1); /* yes, you can, because XFA_AllocFrames() uses AllocVec() */
  730.  
  731.     XFA_SetFramesArray(anim2,anim2frames);
  732.     XFA_FreeAnim();
  733.     FreeVec(anim2); /* yes, you can, because XFA_AllocFrames() uses AllocVec() */
  734.     
  735. ------------------------------------------------------------------------------
  736.  
  737. FUNCTION:
  738.  
  739.     XFA_FreeAnim()
  740.  
  741. PROTO:
  742.  
  743.     void __asm __saveds LIBXFA_FreeAnim(void);
  744.  
  745. ACTION:
  746.  
  747.     Frees all the currently used animation frames (linked to frames array)
  748.     but leaves the frames array allocated.
  749.         
  750. ARGUMENTS:
  751.  
  752.  
  753. BUGS:
  754.  
  755.     
  756. NOTE:
  757.  
  758.     It is safe to call this, even if there is no frames array.
  759.  
  760. ------------------------------------------------------------------------------
  761.  
  762. FUNCTION:
  763.  
  764.     XFA_AnimMem()
  765.  
  766. PROTO:
  767.  
  768.     LONG __asm __saveds LIBXFA_AnimMem(void);
  769.     
  770. ACTION:
  771.  
  772.     Returns the size in bytes of the animation currently in memory.
  773.         
  774. ARGUMENTS:
  775.  
  776.  
  777. BUGS:
  778.  
  779.     
  780. NOTE:
  781.  
  782.     It is safe to call this, even if there is no frames array.
  783.  
  784. ------------------------------------------------------------------------------
  785.  
  786. FUNCTION:
  787.  
  788.     XFA_AnimFrames()
  789.  
  790. PROTO:
  791.  
  792.     LONG __asm __saveds LIBXFA_AnimFrames(void);
  793.  
  794.  
  795. ACTION:
  796.  
  797.     Returns the size in frames of the animation currently in memory.
  798.         
  799. ARGUMENTS:
  800.  
  801.  
  802. BUGS:
  803.  
  804.     
  805. NOTE:
  806.  
  807.     It is safe to call this, even if there is no frames array.
  808.  
  809. ------------------------------------------------------------------------------
  810.  
  811. FUNCTION:
  812.  
  813.     XFA_SaveAnim(filename)
  814.  
  815. PROTO:
  816.  
  817.     LONG __asm __saveds LIBXFA_SaveAnim(register __a0 char * );
  818.     
  819. ACTION:
  820.  
  821.     Save the animation held into current frames array in IFF-XFA format.
  822.     Returns 0 if OK or iff.library error code (IFFERR_#?).
  823.             
  824. ARGUMENTS:
  825.  
  826.     filename = complete path and filename of destination file
  827.  
  828. BUGS:
  829.  
  830.     
  831. NOTE:
  832.  
  833.  
  834. ------------------------------------------------------------------------------
  835.  
  836. FUNCTION:
  837.  
  838.     XFA_LoadAnim(filename,xfa_head,xfa_cmap,mode)
  839.  
  840. PROTO:
  841.  
  842.     LONG __asm __saveds LIBXFA_LoadAnim(register __a0 char * , register __a1 struct XFA_Head * , register __a2 struct XFA_CMap * , register __d0 BOOL );
  843.     
  844. ACTION:
  845.  
  846.     Multi function IFF-XFA load routine that allows to:
  847.     - check if filename is IFF-XFA
  848.     - load an animation into frames array
  849.     - load only xfa_head and xfa_cmap from an IFF-XFA animation
  850.     Returns 0 if OK or iff.library error code (IFFERR_#?).
  851.         
  852. ARGUMENTS:
  853.  
  854.     filename =    complete path and filename of source file
  855.     xfa_head =    pointer to user's allocated XFA_Head structure
  856.                     NULL to use internal library-allocated one.
  857.     xfa_cmap =    pointer to user's allocated XFA_CMap structure
  858.                     NULL to use internal library-allocated one.
  859.     mode =        TRUE to load the whole animation
  860.                     FALSE to load only xfa_head and xfa_cmap
  861.  
  862. BUGS:
  863.  
  864.     
  865. NOTE:
  866.  
  867.     If mode = TRUE, this function replaces any animation already in memory
  868.     issuing a XFA_FreeAnim() before loading the frames.
  869.     The animation will be loaded until there is space into frames-array
  870.     or in memory.
  871.     If you don't know the size (in frames) of the animation to be loaded,
  872.     it is a good thing to first get its xfa_head and allocate enogh frames
  873.     to load it all (reading the needed amount of frames from xfa_head->NFrames).
  874.     You can easily read the palette of an xfa animation simply putting your
  875.     own XFA_CMap pointer into the right parameter, before calling XFA_LoadAnim().
  876.     Note also that current packmode can be changed from this function, even if
  877.     it fails to load an animation.
  878.  
  879. ------------------------------------------------------------------------------
  880.  
  881. FUNCTION:
  882.  
  883.     XFA_PosOnFrame(frame)
  884.  
  885. PROTO:
  886.  
  887.     void __asm __saveds LIBXFA_PosOnFrame(register __d0 LONG );
  888.  
  889. ACTION:
  890.  
  891.     Inits internal buffers for subsequential XFA_PutFrame() calls.
  892.     Returns TRUE if OK or FALSE if it cannot init buffers (no memory or frame
  893.     out of range).
  894.         
  895. ARGUMENTS:
  896.  
  897.     frame = number of frame to position to
  898.  
  899. BUGS:
  900.  
  901.     
  902. NOTE:
  903.  
  904.     Please refer to examples.
  905.  
  906. ------------------------------------------------------------------------------
  907.  
  908. FUNCTION:
  909.  
  910.     XFA_PutFrame(frame)
  911.  
  912. PROTO:
  913.  
  914.     BOOL __asm __saveds LIBXFA_PutFrame(register __d0 LONG );
  915.  
  916. ACTION:
  917.  
  918.     Compresses the frame and puts it in the frames array.
  919.     Returns TRUE if OK or FALSE if it cannot compress the frame    (no memory
  920.     or frame out of range).
  921.         
  922. ARGUMENTS:
  923.  
  924.     frame = number of frame to work on
  925.  
  926. BUGS:
  927.  
  928.     
  929. NOTE:
  930.  
  931.     This function also prepares internal buffers for a subsequential call to
  932.     XFA_PutFrame(), so there's no need to issue a XFA_PosOnFrame() for each
  933.     frame.
  934.     This can be done only with sequential frames.
  935.     To put frames into the frames array randomly, a XFA_PosOnFrame(f) must
  936.     be issued before every XFA_PutFrame(f).
  937.     If packmode if 16BitI or 32BitI, extra unused rasterlines will be cleared
  938.     automatically before compressing the frame.
  939.     This is a litte example of how to pack two sequencies of frames:
  940.  
  941.     .
  942.     .
  943.     .
  944.     c = 6
  945.     XFA_PosOnFrame(c);
  946.     /* render here */
  947.     XFA_PutFrame(c); c++;
  948.     /* render here */
  949.     XFA_PutFrame(c); c++;
  950.     /* render here */
  951.     XFA_PutFrame(c); c++;
  952.     /* render here */
  953.     XFA_PutFrame(c); c++;
  954.     /* render here */
  955.     XFA_PutFrame(c); c++;
  956.     .
  957.     .
  958.     c = 40
  959.     XFA_PosOnFrame(c);
  960.     /* render here */
  961.     XFA_PutFrame(c); c++;
  962.     /* render here */
  963.     XFA_PutFrame(c); c++;
  964.     /* render here */
  965.     XFA_PutFrame(c); c++;
  966.     /* render here */
  967.     XFA_PutFrame(c); c++;
  968.     /* render here */
  969.     XFA_PutFrame(c); c++;
  970.     .
  971.     .
  972.  
  973.     Please refer to examples.
  974.  
  975. ------------------------------------------------------------------------------
  976.  
  977. FUNCTION:
  978.  
  979.     XFA_PutSkip(frame)
  980.  
  981. PROTO:
  982.  
  983.     BOOL __asm __saveds LIBXFA_PutSkip(register __d0 LONG );
  984.  
  985. ACTION:
  986.  
  987.     Puts a skip (no delta information) frame into the frames array.
  988.     Frees any other previous information in that frames array position.
  989.     Returns TRUE if OK or FALSE if it fails (no memory or frame out of
  990.     range).
  991.         
  992. ARGUMENTS:
  993.  
  994.     frame = number of frame to work on
  995.  
  996. BUGS:
  997.  
  998.     
  999. NOTE:
  1000.  
  1001.     This function is used internally by X-DVE but can be useful to    init all
  1002.     the frames array with the predefined skip value for current pack screen.
  1003.     As definition, a skip frame will be ignored during decompression, even
  1004.     if it will be considered for timings as a delay of 1/50 of sec (1/60
  1005.     for NTSC).
  1006.  
  1007. ------------------------------------------------------------------------------
  1008.  
  1009. FUNCTION:
  1010.  
  1011.     XFA_IsSkip(frame)
  1012.  
  1013. PROTO:
  1014.  
  1015.     BOOL __asm __saveds LIBXFA_IsSkip(register __d0 LONG );
  1016.  
  1017. ACTION:
  1018.  
  1019.     Returns TRUE if the frame is a skip (ignore, no delta information) one.
  1020.         
  1021. ARGUMENTS:
  1022.  
  1023.     frame = number of frame to work on
  1024.  
  1025. BUGS:
  1026.  
  1027.     
  1028. NOTE:
  1029.  
  1030.     This function is used internally from X-DVE.
  1031.  
  1032. ------------------------------------------------------------------------------
  1033.  
  1034. FUNCTION:
  1035.  
  1036.     XFA_Play(loop,autopause,waitstart,slow)
  1037.  
  1038. PROTO:
  1039.  
  1040.     BOOL __asm __saveds LIBXFA_Play(register __d0 BOOL , register __d1 BOOL , register __d2 BOOL ,  register __d3 BOOL);
  1041.  
  1042. ACTION:
  1043.  
  1044.     Executes the animation stored in the frames array.
  1045.     Returns TRUE if ok or (only under OS3.0+) FALSE if it cannot allocate
  1046.     the required DBufInfo structure.
  1047.         
  1048. ARGUMENTS:
  1049.  
  1050.     loop =        Infinite loop mode.
  1051.                     TRUE: does an infinite loop play.
  1052.                     FALSE: does a single shot play.
  1053.  
  1054.     autopause = Pause mode.
  1055.                     TRUE: pauses the animation automatically everytime there are
  1056.                     no objects moving on the screen.
  1057.                     FALSE: executes the animation respecting the real animation
  1058.                     timings.
  1059.  
  1060.     waitstart =    User start mode.
  1061.                     TRUE: start to play only when the user clicks and releases
  1062.                     the left mouse button.
  1063.                     FALSE: starts to play immediately, without waiting.
  1064.  
  1065.     slow         =    Slow mode.
  1066.                     TRUE: The animation is played at half speed.
  1067.                     FALSE: The animation is playes at full speed.
  1068.  
  1069.  
  1070. BUGS:
  1071.  
  1072.     
  1073. NOTE:
  1074.  
  1075.     This function temporarily disables all the multitasking facilities of
  1076.     Amiga Operating System: Use with care.
  1077.     During the play, mouse buttons can be used as follows:
  1078.     Left Mouse Button:    start the animation
  1079.                                 restart from an autopause
  1080.                                 if autopause = false : pause execution until release
  1081.     Right Mouse Button:    exit the animation if in autopause
  1082.                                 if autopause = false and Left Mouse Button : exit the
  1083.                                 animation
  1084.  
  1085.     Rather complex to explain, intuitive during play.
  1086.  
  1087. ------------------------------------------------------------------------------
  1088.  
  1089. FUNCTION:
  1090.  
  1091.     XFA_UseHead(xfa_head)
  1092.  
  1093.  
  1094. PROTO:
  1095.  
  1096.     void __asm __saveds LIBXFA_UseHead(register __a0 struct XFA_Head * );
  1097.  
  1098. ACTION:
  1099.  
  1100.     'Uses' the supplied xfa_head settings.
  1101.         
  1102. ARGUMENTS:
  1103.  
  1104.     xfa_head =    pointer to user's XFA_Head structure
  1105.                     if NULL, use internally handled structure.
  1106.  
  1107. BUGS:
  1108.  
  1109.     
  1110. NOTE:
  1111.  
  1112.     This function is here for completeness, and can be modified in the next
  1113.     issues of the library.
  1114.     Actually it simply sets internal packmode according to XFA_Head.Flags
  1115.     bits.
  1116.     However, it can be used when you have multiple XFA_Head structures to refer
  1117.     to.
  1118.  
  1119. ------------------------------------------------------------------------------
  1120.  
  1121. FUNCTION:
  1122.  
  1123.     XFA_UseCMap(screen,xfa_cmap)
  1124.  
  1125. PROTO:
  1126.  
  1127.     void __asm __saveds LIBXFA_UseCMap(register __a0 struct Screen * , register __a1 struct XFA_CMap * );
  1128.  
  1129. ACTION:
  1130.  
  1131.     'Uses' supplied xfa_cmap settings on the screen.
  1132.         
  1133. ARGUMENTS:
  1134.  
  1135.     screen =     pointer to user's screen where XFA_CMap must be applied
  1136.                     if NULL, use destination XFA_SetPack() screen.
  1137.  
  1138.     xfa_cmap =    pointer to user's XFA_CMap structure
  1139.                     if NULL, use internally handled structure.
  1140.  
  1141. BUGS:
  1142.  
  1143.     
  1144. NOTE:
  1145.  
  1146.     This function is here for completeness, and can be modified in the next
  1147.     issues of the library.
  1148.     Actually it simply applies the palette in XFA_CMap to the screen.
  1149.     It is safe only to call this function inside a XFA_OpenPackStuff() - 
  1150.     XFA_ClosePackStuff(), and you must take care if the destination screen
  1151.     is opened.
  1152.     
  1153. ------------------------------------------------------------------------------
  1154.  
  1155. FUNCTION:
  1156.  
  1157.     XFA_OpenPlayStuff(wbmodeid)
  1158.  
  1159. PROTO:
  1160.  
  1161.     BOOL __asm __saveds LIBXFA_OpenPlayStuff(DREG0 BOOL wbmodeid);
  1162.  
  1163. ACTION:
  1164.  
  1165.     Allocates and inits all the stuff needed to play a sequence of frames,
  1166.     referring to the settings in XFA_Head, XFA_CMap internal structures.
  1167.     Returns TRUE if OK or FALSE if function fails to open the play screen
  1168.     and double buffering bitmaps.
  1169.             
  1170. ARGUMENTS:
  1171.  
  1172.     wbmodeid =    force a wb-like screen
  1173.                     TRUE: open play stuff forcing the output on a workbench-like
  1174.                     mode id.
  1175.                     FALSE: open play stuff forcing the output on a PAL screen.
  1176.  
  1177. BUGS:
  1178.  
  1179.     
  1180. NOTE:
  1181.  
  1182.     This function fails if there is not enough memory to allocate the
  1183.     required play stuff.
  1184.     Forcing a wb-like screen, can be useful for viewing animations on Amigas
  1185.     that cannot display PAL videomodes (attached to a VGA only monitor,for
  1186.     example).
  1187.     This means that xfa animations will be played according to wb display
  1188.     refresh frequency and overscan, but they may appear too much fast and
  1189.     sometimes out of the display clip boundaries.
  1190.     Under OS 3.0+ this function uses the BestModeID() when forcing a wb-like
  1191.     mode, while OS 2.0+ users (upgrade your OS !) will sometimes get worse
  1192.     results (have you upgraded ?).
  1193.     It is NOT safe to call this function if internal library-allocated XFA_Head
  1194.     and XFA_CMap structures are not correctly initialized.
  1195.  
  1196. ------------------------------------------------------------------------------
  1197.  
  1198. FUNCTION:
  1199.  
  1200.     XFA_ClosePlayStuff()
  1201.  
  1202. PROTO:
  1203.  
  1204.     void __asm __saveds LIBXFA_ClosePlayStuff(void);
  1205.  
  1206. ACTION:
  1207.  
  1208.     Frees all the stuff opened by XFA_OpenPlayStuff().
  1209.         
  1210. ARGUMENTS:
  1211.  
  1212.  
  1213. BUGS:
  1214.  
  1215.     
  1216. NOTE:
  1217.  
  1218.     It is safe to call this function, even if play stuff does not exist.
  1219.     
  1220. ------------------------------------------------------------------------------
  1221.  
  1222. FUNCTION:
  1223.  
  1224.     XFA_HeadPtr()
  1225.  
  1226. PROTO:
  1227.  
  1228.     struct XFA_Head * __asm __saveds LIBXFA_HeadPtr(void);
  1229.  
  1230. ACTION:
  1231.  
  1232.     Returns the internal library-allocated XFA_Head structure pointer.
  1233.         
  1234. ARGUMENTS:
  1235.  
  1236.  
  1237. BUGS:
  1238.  
  1239.     
  1240. NOTE:
  1241.  
  1242.     Useful to READ XFA_Head settings (WRITING into this structure is really
  1243.     dangerous, expecially having already an animation in memory).
  1244.     
  1245. ------------------------------------------------------------------------------
  1246.  
  1247. FUNCTION:
  1248.  
  1249.     XFA_CMapPtr()
  1250.  
  1251. PROTO:
  1252.  
  1253.     struct XFA_CMap * __asm __saveds LIBXFA_CMapPtr(void);
  1254.  
  1255. ACTION:
  1256.  
  1257.     Returns the internal library-allocated XFA_CMap structure pointer.
  1258.         
  1259. ARGUMENTS:
  1260.  
  1261.  
  1262. BUGS:
  1263.  
  1264.     
  1265. NOTE:
  1266.  
  1267.     Useful to READ XFA_CMap settings (WRITING into this structure is not 
  1268.     too dangerous, but can be easily avoided in order to change animation's
  1269.     palette. See XFA_SetPack() function).
  1270.         
  1271. ------------------------------------------------------------------------------
  1272.  
  1273. FUNCTION:
  1274.  
  1275.     XFA_ChangePackBitMap(bitmap)
  1276.  
  1277. PROTO:
  1278.  
  1279.     void __asm __saveds LIBXFA_ChangePackBitMap(register __a0 struct BitMap * );
  1280.  
  1281. ACTION:
  1282.  
  1283.     Changes the internal source bitmap pointer which PosOnFrame(), PutFrame(),
  1284.     PutSeqFrame() refer for packing a frame.
  1285.             
  1286. ARGUMENTS:
  1287.  
  1288.     bitmap =        pointer to the new source bitmap
  1289.  
  1290. BUGS:
  1291.  
  1292.     
  1293. NOTE:
  1294.  
  1295.     This function is here to allow the packing of double (or more) buffered
  1296.     animations (like Anim5/7/x) whose frames must be unpacked into 2 different
  1297.     bitmaps (one for the even, one for the odd frame).
  1298.     Please, refer to the examples.
  1299.         
  1300. ------------------------------------------------------------------------------
  1301.  
  1302. FUNCTION:
  1303.  
  1304.     XFA_PutSeqFrame(frame)
  1305.  
  1306. PROTO:
  1307.  
  1308.     BOOL __asm __saveds LIBXFA_PutSeqFrame(register __d0 LONG );
  1309.  
  1310. ACTION:
  1311.  
  1312.     Compresses the frame and puts it in the frames array.
  1313.     Returns TRUE if OK or FALSE if it cannot compress the frame    (no memory
  1314.     or frame out of range).
  1315.         
  1316. ARGUMENTS:
  1317.  
  1318.     frame = number of frame to work on
  1319.  
  1320. BUGS:
  1321.  
  1322.     
  1323. NOTE:
  1324.     
  1325.     The differences from XFA_PutFrame() ?
  1326.     XFA_PutFrame() in conjunction with XFA_PosOnFrame() allows easy random
  1327.     access for packing xfa animations.
  1328.     This function is here to help the handling of sequential-only problems
  1329.     like anim5/7/x to xfa conversions.
  1330.     XFA_PutFrame() does some undesired stuff that is both unuseful and
  1331.     incorrect to solve the above problem, so that's why XFA_PutSeqFrame()
  1332.     is here.
  1333.     XFA_PutSeqFrame() keeps track of the previous odd/even frames automatically,
  1334.     so there's no need for the users to do this.
  1335.     This function also prepares internal buffers for a subsequential call to
  1336.     XFA_PutSeqFrame(), so there's no need to issue a XFA_PosOnFrame() for each
  1337.     frame.
  1338.     If packmode if 16BitI or 32BitI, extra unused rasterlines will be cleared
  1339.     automatically before compressing the frame.
  1340.     Please refer to examples.
  1341.  
  1342. ------------------------------------------------------------------------------
  1343.  
  1344. FUNCTION:
  1345.  
  1346.     XFA_SaveScreen(screen,filename)
  1347.  
  1348. PROTO:
  1349.  
  1350.     LONG __asm __saveds LIBXFA_SaveScreen(register __a0 struct Screen * , register __a1 char * );
  1351.  
  1352. ACTION:
  1353.  
  1354.     Saves a standard Amiga screen in IFF-ILBM format.
  1355.     Returns 0 if OK or iff.library error code (IFFERR_#?).
  1356.         
  1357. ARGUMENTS:
  1358.  
  1359.     screen =        pointer to the screen to save
  1360.     filename =    name of the iff file to write
  1361.  
  1362. BUGS:
  1363.  
  1364.     
  1365. NOTE:
  1366.  
  1367.     This function is here for completeness.
  1368.     IFF-ILBM write code is the one furnished from CBM in NewIff39 archive.
  1369.     For this reason, I don't know if it's fully bug free or not.
  1370.     If you have faith in Carolynn Scheppner, the mother of all ilbm
  1371.     handlers .........
  1372.     
  1373. ------------------------------------------------------------------------------
  1374.  
  1375. FUNCTION:
  1376.  
  1377.     XFA_OpenRead(filename,head,cmap)
  1378.  
  1379. PROTO:
  1380.  
  1381.     struct IFFHandle * __asm __saveds LIBXFA_OpenRead(register __a0 char * , register __a1 struct XFA_Head * , register __a2 struct XFA_CMap * );
  1382.  
  1383. ACTION:
  1384.  
  1385.     This function performs the following actions:
  1386.     - opens an XFA file for reading.
  1387.     - (if file is xfa) loads XFA_Head and XFA_Cmap chunks.
  1388.     - (if file is xfa) sets current packmode for library functions.
  1389.     
  1390.     Returns a pointer to an IFFHandle struct.
  1391.     Returns NULL if it fails to open the file or if the file is not xfa.
  1392.         
  1393. ARGUMENTS:
  1394.  
  1395.     filename =    complete path and filename of source xfa file
  1396.     xfa_head =    pointer to user's allocated XFA_Head structure
  1397.                     NULL to use internal library-allocated one.
  1398.     xfa_cmap =    pointer to user's allocated XFA_CMap structure
  1399.                     NULL to use internal library-allocated one.
  1400.  
  1401. BUGS:
  1402.  
  1403.     
  1404. NOTE:
  1405.  
  1406. ------------------------------------------------------------------------------
  1407.  
  1408. FUNCTION:
  1409.  
  1410.     XFA_ReadFrame(iff,mem)
  1411.  
  1412. PROTO:
  1413.  
  1414.     LONG __asm __saveds LIBXFA_ReadFrame(register __a0 struct IFFHandle * , register __a1 struct Mem * );
  1415.  
  1416. ACTION:
  1417.  
  1418.     Reads a single xfa frame from the stream allocating enough ram to store it.
  1419.     Returns 0 if OK or iff.library error code (IFFERR_#?).
  1420.         
  1421. ARGUMENTS:
  1422.  
  1423.     iff     =    pointer to a valid IFFHandle (possibly opened with XFA_OpenRead())
  1424.     mem    =    pointer to a previously allocated mem structure where this function
  1425.                 will set all appropriate fields.
  1426.  
  1427. BUGS:
  1428.  
  1429.     
  1430. NOTE:
  1431.  
  1432.     This function allocates memory, so take care of freeing every loaded
  1433.     frame as soon as you've used it.
  1434.  
  1435. ------------------------------------------------------------------------------
  1436.  
  1437. FUNCTION:
  1438.  
  1439.     XFA_FreeFrame(mem)
  1440.  
  1441. PROTO:
  1442.  
  1443.     void __asm __saveds LIBXFA_FreeFrame(register __a0 struct Mem * );
  1444.  
  1445. ACTION:
  1446.  
  1447.     Frees a single xfa frame from memory
  1448.         
  1449. ARGUMENTS:
  1450.  
  1451.     mem    =    pointer to a previously allocated mem structure indicating the
  1452.                 frame in memory.
  1453.  
  1454. BUGS:
  1455.  
  1456.     
  1457. NOTE:
  1458.  
  1459.     As Mem structure will probabily grow or change, you are kindly requested
  1460.     to make use of this function instead of trying to free frames with your
  1461.     own code.
  1462.     This will ensure future compatibility with new releases of xfa.library.
  1463.     Internal sanity check covers only NULL mem->Ptr fields, but I have to remind
  1464.     you that all arguments are intended to be safe and consistent.
  1465.  
  1466. ------------------------------------------------------------------------------
  1467.  
  1468. <EOF>
  1469.